ATSUMatchFontsToText

OSStatus ATSUMatchFontsToText (
                     ATSUTextLayout iTextLayout,
                     UniCharArrayOffset iTextStart,
                     UniCharCount iTextLength,
                     ATSUFontID *oFont,
                     UniCharArrayOffset *oChangedOffset,
                     UniCharCount *oChangedLength);

iTextLayout

A reference of type ATSUTextLayout. Pass a reference to an initialized text layout object. You cannot pass NULL for this parameter.

iTextStart

A value of type UniCharArrayOffset. Pass the edge offset of the beginning of the range of text that you want to scan for character(s) that could not be drawn with the assigned font. To indicate the beginning of the text buffer, pass the constant kATSUFromTextBeginning, described in Text Offset Constant. If you pass an edge offset that is outside the text buffer, ATSUMatchFontsToText returns the result code kATSUInvalidTextRangeErr.

iTextLength

A value of type UniCharCount. Pass the length of the of the range of text that you want to scan for character(s) that could not be drawn with the assigned font. To indicate the beginning of the text buffer, pass the constant kATSUToTextEnd, described in Text Length Constant. If you pass a length that is outside the text buffer, ATSUMatchFontsToText returns the result code kATSUInvalidTextRangeErr.

oFont

A pointer to a value of type ATSUFontID. On return, the substitute font recommended by ATSUMatchFontsToText.

oChangedOffset

A pointer to a value of type UniCharArrayOffset. On return, the edge offset of the beginning of the range of text containing character(s) whose font does not have all the glyphs necessary to draw it.

oChangedLength

A pointer to a value of type UniCharCount. On return, the length of the range of text containing character(s) whose font does not have all the glyphs necessary to draw it.

function result

A result code. The result code noErr indicates that all the characters can be rendered with their currently assigned fonts. The result code kATSUFontsMatched indicates that at least one character could not be rendered with its currently assigned font. In this case, all the characters in the specified text range cannot be drawn with their currently assigned font, but can be drawn with the font passed back in the oFont parameter. The result code kATSUFontsNotMatched indicates that at least one character could not be rendered with its currently assigned font or with any currently active font. In this case, all the characters in the specified text range can only be rendered by the last resort font, and the value of oFont is set to kATSUInvalidFontID. For a list of other ATSUI-specific result codes, see Result Codes.

DISCUSSION

The ATSUMatchFontsToText function obtains the first subrange of text whose character(s) cannot be drawn with the assigned font and recommends a substitute font. It does not actually perform font substitutions. If you want ATSUI to perform font substitutions, call the function ATSUSetTransientFontMatching.

ATSUMatchFontsToText scans all valid fonts on the user's system for a substitute font. This is the default search behavior used if you do not call the function ATSUSetFontFallbacks, or if you pass the constant kATSUDefaultFontFallbacks in the iFontFallbackMethod parameter of the function.

ATSUMatchFontsToText looks for characters in a specified range of text that cannot be drawn with the fonts in the style run. It passes back an offset to the first range of text that could not be drawn and suggests an alternative font to use. For example, if the subrange of text for which you wanted to perform font substitution was the text "abcde", and the characters `c' and `d' could not be drawn with the current font (that is, the font in the styles for this text layout object) but could be drawn with font F, and the character `e' could either be drawn with the current font or could not be drawn with font F, then ATSUMatchFontsToText will pass back the ATSUIFontID of font F in the oFont parameter and will set oChangedOffset to 2 and oChangedLength to 2.

If the function returns the result codes kATSUFontsMatched or kATSUFontsNotMatched, you should update the input range and call ATSUMatchFontsToText again to make sure that all the characters in the range could be drawn.

SPECIAL CONSIDERATIONS

ATSUMatchFontsToText may allocate memory in your application heap, unless you designate a different heap by calling the function ATSUCreateMemorySetting.

VERSION NOTES

Available beginning with ATSUI 1.0.